Fritz: All Fritz/All Fritz.zip/All Fritz/FILES/PROGNG_C/SDB.LZH/SDB.TXT

Text File | 1984-01-06 | 24.8 KB | 1,006 lines

                       SDB - a Simple Database System

                              by David Betz
                            114 Davenport Ave.
                           Manchester, NH 03103
                              [phone]

                        Converted to the IBM/PC by
                              David N. Smith
                            44 Ole Musket Lane
                            Danbury, CT  06810
                              [phone]


        1.0  INTRODUCTION

        SDB is a simple database manager for small systems.  It  was
        developed  to  provide  a relatively low overhead system for
        storing data  on  machines  with  limited  disk  and  memory
        resources.   The current version runs on a PDT-11/150 with 2
        RX01 floppy disk drives and 60K bytes of  memory  under  the
        RT-11 operating system.  (it also runs on the VAX under VMS)

        SDB was originally intended  to  be  a  relational  database
        system, so many of the terms used in describing it are taken
        from the relational database literature.  Within the context
        of SDB the user can safely make the following associations:

             1.  RELATION can be taken to mean FILE

             2.  TUPLE can be taken to mean RECORD

             3.  ATTRIBUTE can be taken to mean FIELD

        It should be noted that SDB is not a  relationally  complete
        system.   It  provides  the relational operations of SELECT,
        PROJECT, and JOIN, but does not provide the  set  operations
        of  UNION,  INTERSECTION,  or  DIFFERENCE  as  well  as some
        others.


        2.0  RELATION FILE FORMATS

        SDB maintains a separate file for  each  relation  that  the
        user  creates.  This file contains a header block containing
        the definition of the relation including the names and types
        of  all  of the relation's attributes.  The remainder of the
        file contains fixed length records each containing one tuple
        from the relation.

        Tuples can be of three types:

             1.  active - tuples that contain actual active data

             2.  deleted - tuples that have been deleted

             3.  unused - tuples that haven't been used yet

        SDB - a Simple Database System                        Page 2


        Initially, all tuples are  unused.   When  a  new  tuple  is
        stored  into  a  relation,  the  first unused tuple is found
        (they are all contiguous at the end of the  relation  file).
        The new tuple is stored as an active tuple.

        When a tuple is deleted, it is marked as  such.   The  space
        previously  allocated  to  the  deleted tuple is left unused
        until the relation is compressed.

        It is possible that when attempting to store a new tuple, no
        unused  tuple can be found even though the relation contains
        fewer than the maximum active  tuples.   This  happens  when
        tuples  have  been  deleted since the time the relation file
        was last compressed.

        The compress function  allows  all  of  the  space  lost  by
        deleting tuples to be regained.  It does this by copying all
        of the active tuples as far backward in the file as possible
        leaving  all  of  the  available space toward the end of the
        file.



        3.0  SELECTION EXPRESSIONS

        A selection expression specifies a set of tuples over  which
        some  SDB  operation  is  to  be executed.  The syntax for a
        selection expression is:

        <rse>           ::= <rnames> [ where <boolean> ]
        <rnames>        ::= <rname> [ , <rname> ] ...
        <rname>         ::= <relation-name> [ <alias> ]

        When a single relation name  is  specified  in  a  selection
        expression,  each  tuple  within  that  relation  becomes  a
        candidate for selection.

        When more than one relation name is  specified,  the  tuples
        are  formed  by  taking  the  cross product of all specified
        relations.  If a relation is to be crossed with  itself,  an
        alias must be given to one or both of the occurances of that
        relation name in the selection expression.  This allows  SDB
        to determine which relation occurance is being refered to in
        the boolean part of the selection expression.

        After the set of candidate tuples is determined, the boolean
        expression  is evaluated for each candidate.  The candidates
        for which the boolean expression evaluates  to  TRUE  become
        the selected tuples.

        SDB - a Simple Database System                        Page 3


        4.0  INITIALIZATION FILE AND COMMAND FILES

        When SDB is first run,  it  attempts  to  read  and  process
        commands  from  a  file  named "SDB.INI".  This file usually
        contains macro definitions, but can contain  any  valid  SDB
        command.   In  addition,  it  is possible to process command
        files from within SDB.   This  is  done  by  typing  an  '@'
        followed by the command file name after the SDB prompt.



        5.0  FILE NAMES

        Whenever a file name is allowed in the syntax for a command,
        it  is  possible  to  use  either  an identifier or a quoted
        string.  An identifier is interpreted as the file name and a
        string  is  interpreted  as  a full file specification.  The
        string form allows for the  specification  of  an  alternate
        device or extension.



        6.0  FORM DEFINITION FILES

        A form  definition  file  contains  a  template  into  which
        attribute  values  are substituted during a print operation.
        There are two types of information that can be included in a
        form definition:

             1.  Literal text

             2.  Attribute references

        Attribute references are indicated by placing  the  name  of
        the  attribute  being  referenced  between  a  pair of angle
        brackets.  Literal text is anything that is not enclosed  in
        angle brackets.

        SDB - a Simple Database System                        Page 4


        Example:
        ________

        print using test amount,category from checks;

        Where test.frm contains:

        Amount: <amount>
        Category: <category>


        7.0  ALIASES FOR RELATIONS AND ATTRIBUTES

        When a relation or attribute name is specified  in  a  print
        statement,  it  is possible to provide an alternate name for
        that relation or attribute.  This is useful  for  relations,
        when  it  is  necessary to join a relation to itself.  It is
        useful for attributes when it is  desired  that  the  column
        headers  in  a  table be different from the actual attribute
        names.  Also, alternate  attribute  names  can  be  used  in
        references  to that attribute in the where clause as well as
        in a  form  definition  file.   The  syntax  for  specifying
        aliases is:

            <name> <alias>


        Example:
        ________

        print using test amount a,category c from checks;

        Where test.frm contains:

        Amount: <a>
        Category: <c>

        SDB - a Simple Database System                        Page 5


        8.0  BOOLEAN EXPRESSIONS

        The syntax for boolean expressions:

        <expr>          ::= <land> [ '|' <land> ]
        <land>          ::= <relat> [ '&' <relat> ]
        <relat>         ::= <primary> [ <relop> <primary> ]
        <primary>       ::= <term> [ <addop> <term> ]
        <term>          ::= <unary> [ <mulop> <unary> ]
        <unary>         ::= <factor> | <unop> <unary>
        <factor>        ::= <operand> | '(' <expr> ')'
        <operand>       ::= <number> | <string> | <attribute>
        <attribute>     ::= [ <rname> . ] <aname>
        <relop>         ::= '=' | '<>' | '<' | '>' | '<=' | '>='
        <addop>         ::= '+' | '-'
        <mulop>         ::= '*' | '/'
        <unop>          ::= '+' | '-' | '~'


        Operators:

             1.  '=' - equal

             2.  '<>' - not equal

             3.  '<' - less than

             4.  '>' - greater than

             5.  '<=' - less than or equal

             6.  '>=' - greater than or equal

             7.  '+' - addition or unary plus (not implemented)

             8.  '-' - subraction or unary minus (not implemented)

             9.  '*' - multiplication (not implemented)

            10.  '/' - division (not implemented)

            11.  '&' - logical and

            12.  '|' - logical or

            13.  '~' - logical not

        Operands:

             1.  number - a string of digits containing at most  one
                 decimal point

             2.  string - a string of characters enclosed in  double
                 quotes

        SDB - a Simple Database System                        Page 6


             3.  attribute - an attribute name optionally  qualified
                 by a relation name


        SDB - a Simple Database System                        Page 7


        9.0  INTERACTIVE COMMAND DESCRIPTIONS

        Function:
        _________

        Create a relation file


        Format:
        _______

        create <rname> ( <alist> ) <size>


        Rules:
        ______

             1.  <rname> is the name of the relation file

             2.  <alist> is a list of attribute definitions  of  the
                 form:

                   <aname> { char | num } <size>

                 where:

                 1.  <aname> is the name of the attribute

                 2.  the type of the attribute is either  "char"  or
                     "num"

                 3.  <size> is the number of bytes allocated to  the
                     attribute value


             3.  <size> is the maximum number of tuples the file  is
                 to hold



        Example:
        ________

        create checks (
            number      num     4
            date        char    8
            payee       char    20
            amount      num     8
            category    char    5
        ) 200

        This command creates a relation file named "checks.sdb" with
        attributes   "number",   "date",   "payee",   "amount",  and
        "category" and space to store 200 tuples.

        SDB - a Simple Database System                        Page 8


        Function:
        _________

        Insert tuples into a relation


        Format:
        _______

        insert <rname>


        Rules:
        ______

             1.  <rname> is the name of a relation

             2.  the user will be prompted for  the  values  of  the
                 attributes for the tuple to be inserted

             3.  a  null  response  to  an  attribute  prompt   will
                 terminate tuple entry

             4.  if a null value is desired, a single space  can  be
                 entered


        SDB - a Simple Database System                        Page 9


        Function:
        _________

        Delete tuples from a set of relations


        Format:
        _______

        delete <rse> ;


        Rules:
        ______

             1.  <rse> is a tuple selection expression

             2.  selected tuples are deleted



        Example:
        ________

        delete checks where category = "junk";

        SDB - a Simple Database System                       Page 10



        Function:
        _________

        Update the values of selected attributes in selected tuples


        Format:
        _______

        update { <attrs> | * } from <rse> ;


        Rules:
        ______

             1.  <attrs> is a list of attribute names to be updated

             2.  * means all attributes

             3.  <rse> is a tuple selection expression

             4.  for each  set  of  selected  tuples,  the  user  is
                 prompted for new values for the selected attributes

             5.  a null response to an attribute prompt will  retain
                 the previous attribute value

             6.  if a null value is desired, a single space  can  be
                 entered



        Example:
        ________

        update amount,category from checks where number > 10;

        SDB - a Simple Database System                       Page 11


        Function:
        _________

        Print a table of values of selected attributes


        Format:
        _______

        print [ using <fname> ] { <attrs> | * } from  <rse>  [  into
        <fname> ] ;


        Rules:
        ______

             1.  using  <fname>  indicates  output  using   a   form
                 definition file (.FRM)

             2.  <attrs> is a list of attribute names to be printed

             3.  * means all attributes

             4.  <rse> is a tuple selection expression

             5.  <fname> is the name of an file to which  the  table
                 will be output (.TXT)

             6.  if the output file name is omitted,  output  is  to
                 the terminal

             7.  for each set of selected tuples, a table  entry  is
                 printed containing the selected attributes



        Example:
        ________

        print payee,amount from checks where category = "junk";

        SDB - a Simple Database System                       Page 12


        Function:
        _________

        Import tuples from a file into a relation


        Format:
        _______

        import <fname> into <rname>


        Rules:
        ______

             1.  <fname> is the name of the input file (.DAT)

             2.  the input file contains the  values  of  the  tuple
                 attributes with each on a separate line

             3.  <rname> is the name of a relation

             4.  tuples are appended to the named relation


        SDB - a Simple Database System                       Page 13


        Function:
        _________

        Export tuples from a relation into a file


        Format:
        _______

        export <rname> [ into <fname> ] ;


        Rules:
        ______

             1.  <rname> is the name of a relation

             2.  <fname> is the name of the output file (.DAT)

             3.  if the output file name is omitted,  output  is  to
                 the terminal

             4.  tuples are written to  the  output  file  with  one
                 attribute value per line


        SDB - a Simple Database System                       Page 14


        Function:
        _________

        Extract the definition of a relation into a file


        Format:
        _______

        extract <rname> [ into <fname> ] ;


        Rules:
        ______

             1.  <rname> is the name of a relation

             2.  <fname> is the name of the output file (.DEF)

             3.  if the output file name is omitted,  output  is  to
                 the terminal

             4.  the definition of the relation is  written  to  the
                 output file


        SDB - a Simple Database System                       Page 15


        Function:
        _________

        Compress a relation file


        Format:
        _______

        compress <rname>


        Rules:
        ______

             1.  <rname> is the name of a relation file

             2.  tuples are copied toward the front of the  relation
                 file  such  that  any  space  freed  by  previously
                 deleted tuples becomes adjacent to the  free  space
                 at the end of the file, thus becoming available for
                 use in inserting new tuples


        SDB - a Simple Database System                       Page 16


        Function:
        _________

        Sort a relation file


        Format:
        _______

        sort <rname> by <sname> { , <sname } ...  ;


        Rules:
        ______

             1.  <rname> is the name of a relation file

             2.  <sname> is the name of  an  attribute  to  sort  on
                 followed optionally by "ascending" or "descending"

             3.  if a sort order  is  not  specified,  ascending  is
                 assumed

             4.  tuples within the  relation  are  sorted  in  place
                 using the attributes indicated


        SDB - a Simple Database System                       Page 17


        Function:
        _________

        Define a macro


        Format:
        _______

        define <mname>


        Rules:
        ______

             1.  <mname> is the name of the macro being defined

             2.  if a macro with the specified name already  exists,
                 it is replaced

             3.  after entering the define command, definition  mode
                 is entered

             4.  definition  mode  is  indicated   by   the   prompt
                 "SDB-DEF>"

             5.  all lines typed in definition mode are added to the
                 macro definition

             6.  a blank line terminates definition mode

             7.  a macro can be deleted by entering a blank line  as
                 the only line in the definition

             8.  after a macro is defined, every  occurance  of  the
                 macro name is replaced by the macro definition


        SDB - a Simple Database System                       Page 18


        Function:
        _________

        Show a macro definition


        Format:
        _______

        show <mname>


        Rules:
        ______

             1.  <mname> is the name of a macro whose definition  is
                 to be shown


        SDB - a Simple Database System                       Page 19


        Function:
        _________

        Print a short help message



        Format:
        _______

        help


        Rules:
        ______

             1.  (none)


        SDB - a Simple Database System                       Page 20


        Function:
        _________

        Exit from SDB


        Format:
        _______

        exit


        Rules:
        ______

             1.  (none)


        SDB - a Simple Database System                       Page 21


        10.0  PROGRAM INTERFACE

        SDB provides a callable program interface to allow  programs
        written  in  DECUS-C  to access relation files.  In order to
        use the call interface, the users program should  be  linked
        with  the SDBUSR.OBJ object library.  Also, additional stack
        space should be allocated at link  time  using  the  /BOTTOM
        qualifier  on  the link command.  /BOTTOM:3000 seems to work
        well, but it is probably possible to get away with less.

        Example:
        ________

        #include <stdio.h>
        #include "sdb.h"

        main()
        {
            DB_SEL *sptr;
            char payee[100],amount[100];

            /* setup retrieval */
            if ((sptr = db_retrieve("checks where amount > 25.00")) == NULL) {
                printf("*** error: %s ***\n",db_ertxt(dbv_errcode));
                exit();
            }

            /* bind user variables to attributes */
            db_bind(sptr,"checks","payee",payee);
            db_bind(sptr,"checks","amount",amount);

            /* loop through selection */
            while (db_fetch(sptr))
                printf("%s\t%s\n",payee,amount);

            /* finish selection */
            db_done(sptr);
        }

        SDB - a Simple Database System                       Page 22


        Function:
        _________

        Setup a tuple retrieval context


        Format:
        _______

        dbptr = db_retrieve(sexpr [ ,arg ]...)


        Rules:
        ______

             1.  sexpr is a pointer to a string containing an rse

             2.  arg is a "printf" argument

             3.  dbptr is a database context pointer

             4.  db_retrieve returns NULL on errors

             5.  on errors, the error code is in dbv_errcode


        SDB - a Simple Database System                       Page 23


        Function:
        _________

        Fetch the next set of tuples from a retrieval context


        Format:
        _______

        db_fetch(dbptr)


        Rules:
        ______

             1.  dbptr is a database context pointer

             2.  updates the values of all bound user variables

             3.  db_fetch returns FALSE if no more tuples  match  or
                 if an error occurs

             4.  on errors, the error code is in dbv_errcode


        SDB - a Simple Database System                       Page 24


        Function:
        _________

        Update the current tuple within a retrieval context


        Format:
        _______

        db_update(dbptr)


        Rules:
        ______

             1.  dbptr is a database context pointer

             2.  db_update returns FALSE if an error occurs

             3.  on errors, the error code is in dbv_errcode


        SDB - a Simple Database System                       Page 25


        Function:
        _________

        Store a new tuple within a retrieval context


        Format:
        _______

        db_store(dbptr)


        Rules:
        ______

             1.  dbptr is a database context pointer

             2.  db_store returns FALSE if an error occurs

             3.  on errors, the error code is in dbv_errcode


        SDB - a Simple Database System                       Page 26


        Function:
        _________

        Bind a user variable to  the  value  of  a  tuple  attribute
        within a retrieval context


        Format:
        _______

        db_bind(dbptr,rname,aname,value)


        Rules:
        ______

             1.  dbptr is a database context pointer

             2.  rname is a pointer to the relation name

             3.  aname is a pointer to the attribute name

             4.  value is a pointer to a character array to  receive
                 the attribute value

             5.  db_bind returns FALSE if an error occurs

             6.  on errors, the error code is in dbv_errcode


        SDB - a Simple Database System                       Page 27


        Function:
        _________

        Get the value  of  a  tuple  attribute  within  a  retrieval
        context


        Format:
        _______

        db_get(dbptr,rname,aname,value)


        Rules:
        ______

             1.  dbptr is a database context pointer

             2.  rname is a pointer to the relation name

             3.  aname is a pointer to the attribute name

             4.  value is a pointer to a character array to  receive
                 the attribute value

             5.  db_get returns FALSE if an error occurs

             6.  on errors, the error code is in dbv_errcode


        SDB - a Simple Database System                       Page 28


        Function:
        _________

        Put the value  of  a  tuple  attribute  within  a  retrieval
        context


        Format:
        _______

        db_put(dbptr,rname,aname,value)


        Rules:
        ______

             1.  dbptr is a database context pointer

             2.  rname is a pointer to the relation name

             3.  aname is a pointer to the attribute name

             4.  value is a pointer to the new value

             5.  db_put returns FALSE if an error occurs

             6.  on errors, the error code is in dbv_errcode


        SDB - a Simple Database System                       Page 29


        Function:
        _________

        Discontinue usage of a retrieval context



        Format:
        _______

        db_done(dbptr)


        Rules:
        ______

             1.  dbptr is a database context pointer


        SDB - a Simple Database System                       Page 30


        Function:
        _________

        Translate an error code to an error message text


        Format:
        _______

        db_ertxt(errcode)


        Rules:
        ______

             1.  errcode is an SDB error code

             2.  db_ertxt returns a pointer  to  the  error  message
                 text